/*
 * Copyright (c) 2010, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

import java.lang.annotation.*;

/**
 * 程序员断言，被注解的方法或构造方法的主体不会对其可变参数执行潜在的不安全操作。
 * 将此注解应用于方法或构造方法会抑制关于<i>不可具体化</i>可变参数（vararg）类型的
 * 未检查警告，并抑制关于调用站点参数化数组创建的未检查警告。
 *
 * <p>除了其 {@link Target @Target} 元注解施加的使用限制外，
 * 编译器还需要对此注解类型实施额外的使用限制；
 * 如果方法或构造方法声明使用 {@code @SafeVarargs} 注解进行注解，
 * 并且满足以下任一条件，则是编译时错误：
 * <ul>
 * <li>声明是固定参数数量的方法或构造方法
 *
 * <li>声明是既不是 {@code static} 也不是 {@code final} 的可变参数方法。
 *
 * </ul>
 *
 * <p>当此注解类型应用于以下情况的方法或构造方法声明时，鼓励编译器发出警告：
 *
 * <ul>
 *
 * <li>可变参数具有可具体化的元素类型，包括基本类型、{@code Object} 和 {@code String}。
 * （此注解类型抑制的未检查警告对于可具体化的元素类型已经不会发生。）
 *
 * <li>方法或构造方法声明的主体执行潜在的不安全操作，
 * 例如对可变参数数组的元素进行赋值，这会产生未检查警告。
 * 某些不安全操作不会触发未检查警告。例如，以下别名操作
 *
 * <blockquote><pre>
 * &#64;SafeVarargs // 实际上并不安全！
 * static void m(List&lt;String&gt;... stringLists) {
 *   Object[] array = stringLists;
 *   List&lt;Integer&gt; tmpList = Arrays.asList(42);
 *   array[0] = tmpList; // 语义上无效，但编译时没有警告
 *   String s = stringLists[0].get(0); // 糟糕，运行时 ClassCastException！
 * }
 * </pre></blockquote>
 *
 * 会导致运行时 {@code ClassCastException}。
 *
 * <p>平台的未来版本可能会强制要求对此类不安全操作产生编译器错误。
 *
 * </ul>
 *
 * @since 1.7
 * @jls 4.7 Reifiable Types
 * @jls 8.4.1 Formal Parameters
 * @jls 9.6.3.7 @SafeVarargs
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
public @interface SafeVarargs {}
